/*
 * Copyright (c) 2013-2018 上海汇数数据. All rights reserved.
 * @(#) OutVO.java 2018-08-08 14:06
 */

package cn.jh.common.core.ret;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.io.Serializable;


/**
 * 外部响应数据基础模型，通常用于网页数据、开放API响应数据等。
 * <pre>{@code
 * Structure:
 * {
 *     "code": "0000",  // return code
 *     "message": "response message",
 *     "description": "More description",
 *     "data": {} // object data|map data, or list []
 * }
 * }</pre>
 *
 * 查询接口可使用 {@link OutVO#ok(String, Object)}，{@link OutVO#data(Object)}；或者错误信息使用
 * {@link OutVO#error(Throwable, String)}。
 * 操作接口可使用 {@link OpsOutVO#ok(String, Object)}，{@link OpsOutVO#ok()}；或者错误信息使用
 * {@link OpsOutVO#fail()} 或者 {@link OpsOutVO#fail(String)}
 *
 * @author Fuchun
 * @since 1.0
 */
public interface OutVO extends Serializable {

    /**
     * 响应给定的消息和数据。默认返回码为 {@value Constants#SUCCESS_CODE}
     *
     * @param message 返回的消息。
     * @param data 响应的数据。
     */
    static OutVO ok(String message, @Nullable Object data) {
        return DefaultOutVO.ok(message, data);
    }

    /**
     * 响应给定的数据。默认返回码为 {@value Constants#SUCCESS_CODE}
     *
     * @param data 返回的数据（可序列化）
     */
    static OutVO data(Object data) {
        return DefaultOutVO.data(data);
    }

    /**
     * 响应一个带异常的消息。返回码为 {@value Constants#ERROR_CODE}
     *
     * @param ex 发生的异常（not null）。
     * @param description 详细的错误说明。
     * @param <X> 发生的异常类型。
     */
    static <X extends Throwable> OutVO error(@NotNull X ex, @Nullable String description) {
        return DefaultOutVO.error(ex, description);
    }

    /**
     * 响应的返回码（业务逻辑响应码）
     */
    String getCode();

    /**
     * 响应的返回码的消息说明。
     */
    String getMessage();

    /**
     * 响应的消息的详细说明。
     */
    String getDescription();

    /**
     * 响应的可序列化的数据。
     */
    Object getData();
}
